All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class quicktime.std.music.MusicData

java.lang.Object
   |
   +----quicktime.QTObject
           |
           +----quicktime.util.QTHandleRef
                   |
                   +----quicktime.util.QTHandle
                           |
                           +----quicktime.std.music.MusicData

public class MusicData
extends QTHandle

MusicData objects contain general information for a Music Track that the TunePlayer uses when it instantiates NoteChannels for the parts contained in the music media. MusicData object's internal data are all aligned on int values (ie. 32bit data segments) so the offsets for getting and setting values in this structure are expressed in terms of these 32bit values.

Data in MusicData is in big endian order and the stuff static methods return values are in the correct big endian format and order to be added to a MusicData object as is. If an application writes its own stuff methods they can return the data in big endian order to ensure compatibility with the existing stuff methods. Thus when music events are added to the MusicData they must be in big endian format and the values retrieved from a constructed MusicData object will be in big endian order.

Many of the macros that are provided in the QuickTimeMusic.h file are translated here as static methods. The names of the macros are represented here with the qtma_ removed and the first letter after the _ is NOT a capital. Thus qtma_StuffRestEvent becomes stuffRestEvent.

An application does NOT need to set the end of sequence marker event if this marker should be set as the last music data element in the MusicData object. The set... and get... calls will check for proper bounds and include a check that allows for the required existence of the end of sequence marker.

kNoteRequestHeaderEventLength: The size (numer of ints) of a kNoteRequestEvent (including its header and footer)

MusicData(int): Create a MusicData object of the specified number of bytes.

controlController(int): Given a stuffed big-endian order QuickTime music event this method will extract the controller number.
controlValue(int): Given a stuffed big-endian order QuickTime music event this method will extract the controller's specified value.
eventType(int): Given a stuffed big-endian order QuickTime music event this method will extract the event type.
generalLength(int): Given a stuffed big-endian order QuickTime music event this method will extract the general event's length from either header or the footer of the general event.
generalSubtype_Footer(int): Given a stuffed big-endian order QuickTime music event this method will extract the general event's sub type from the footer of the general event.
getAtomicInstrument(int): Returns an AtomicInstrument from the specified offset (numer of ints) into the MusicData.
getMusicEvent(int): Returns the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.
getNoteRequest(int): Returns a NoteRequest object from the specified offset (numer of ints) into the MusicData.
getXMusicEvent(int): Returns the stuffed QuickTime extended music event at the specified number of ints into the MusicData.
markerSubtype(int): Given a stuffed big-endian order QuickTime music event this method will extract the marker's sub type.
markerValue(int): Given a stuffed big-endian order QuickTime music event this method will extract the marker's value.
noteDuration(int): Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.
notePitch(int): Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.
noteVelocity(int): Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.
part(int): Given a stuffed big-endian order QuickTime music event this method will extract the part number.
restDuration(int): Given a stuffed big-endian order QuickTime extended music event this method will extract the rest duration.
setAtomicInstrument(int, int, AtomicInstrument): Copies the AtomicInstrument data to the specified offset (numer of ints) into the MusicData.
setMusicEvent(int, int): Sets the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.
setNoteRequest(int, int, NoteRequest): Copies the NoteRequest data to the specified offset (numer of ints) into the MusicData.
setSize(int): Resets the size of the MusicData object to the new size (in bytes).
setXMusicEvent(int, long): Sets the stuffed QuickTime extended music event at the specified number of ints into the MusicData.
stuffControlEvent(int, int, int): Returns an int that is the stuffed representation of the control music event.
stuffGeneralEvent_Footer(int, int): Returns an int that is the stuffed representation of the footer portion of a general music event.
stuffGeneralEvent_Header(int, int): Returns an int that is the stuffed representation of the header portion of a general music event.
stuffMarkerEvent(int, int): Returns an int that is the stuffed representation of the marker music event.
stuffNoteEvent(int, int, int, int): Returns an int that is the stuffed representation of the note music event.
stuffRestEvent(int): Returns an int that is the stuffed representation of the rest music event.
stuffXControlEvent(int, int, int): Returns a long that is the stuffed representation of the extended note music event.
stuffXKnobEvent(int, int, int): Returns a long that is the stuffed representation of the extended note music event.
stuffXNoteEvent(int, int, int, int): Returns a long that is the stuffed representation of the extended note music event.
xControlController(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.
xControlValue(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.
xKnobID(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.
xKnobValue(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.
xNoteDuration(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.
xNotePitch(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.
xNoteVelocity(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.
xPart(long): Given a stuffed big-endian order QuickTime extended music event this method will extract the part number.

kNoteRequestHeaderEventLength

 public static final int kNoteRequestHeaderEventLength

The size (numer of ints) of a kNoteRequestEvent (including its header and footer)

MusicData

 public MusicData(int size) throws QTException

Create a MusicData object of the specified number of bytes. The end of sequence marker is inserted in the last four bytes of the MusicData object.

Parameters:: size - the size in bytes of the required MusicData object

stuffGeneralEvent_Header

 public static int stuffGeneralEvent_Header(int part,
                                            int length)

Returns an int that is the stuffed representation of the header portion of a general music event.

Parameters:: part - the part that the event applies to; length - the length (including the surrounding general event header and footer) of the size of the general event. This size is in bytes.
Returns:: the stuffed representation of this type of music event in big endian order

stuffGeneralEvent_Footer

 public static int stuffGeneralEvent_Footer(int subType,
                                            int length)

Returns an int that is the stuffed representation of the footer portion of a general music event.

Parameters:: part - the part that the event applies to; length - the length (including the surrounding general event header and footer) of the size of the general event. This size is in bytes.
Returns:: the stuffed representation of this type of music event in big endian order

stuffRestEvent

 public static int stuffRestEvent(int duration)

Returns an int that is the stuffed representation of the rest music event.

Parameters:: duration - the duration in the time scale of the TunePlayer or the MusicMedia
Returns:: the stuffed representation of this type of music event in big endian order

stuffNoteEvent

 public static int stuffNoteEvent(int part,
                                  int pitch,
                                  int velocity,
                                  int duration)

Returns an int that is the stuffed representation of the note music event.

Parameters:: part - the part that the note is played by; pitch - the MIDI note pitch of the note - valid range is 32 - 95 (with middle C as 60); velocity - the note-on velocity when the note is played; duration - the duration in the time scale of the TunePlayer or the MusicMedia
Returns:: the stuffed representation of this type of music event in big endian order

stuffControlEvent

 public static int stuffControlEvent(int part,
                                     int control,
                                     int value)

Returns an int that is the stuffed representation of the control music event.

Parameters:: part - the part that the note is played by; control - the number of the controller; value - 8.8 bit fixed point signed controller specific value
Returns:: the stuffed representation of this type of music event in big endian order

stuffMarkerEvent

 public static int stuffMarkerEvent(int markerType,
                                    int markerValue)

Returns an int that is the stuffed representation of the marker music event.

Parameters:: markerType - the type of marker that is required; markerValue - the value applied to the specified marker
Returns:: the stuffed representation of this type of music event in big endian order

stuffXNoteEvent

 public static long stuffXNoteEvent(int part,
                                    int pitch,
                                    int volume,
                                    int duration)

Returns a long that is the stuffed representation of the extended note music event. Extended music events are 2 big endian ints stuffed into a long.

Parameters:: part - the part that the note is played by; pitch - a 8.8 pitch value where the high 8 bits are the MIDI note number and the low 8 bits represent some fractional value of a semitone; velocity - the note-on velocity when the note is played; duration - the duration in the time scale of the TunePlayer or the MusicMedia
Returns:: the stuffed representation of this type of extended music event.

stuffXControlEvent

 public static long stuffXControlEvent(int part,
                                       int control,
                                       int value)

Returns a long that is the stuffed representation of the extended note music event. Extended music events are 2 big endian ints stuffed into a long.

Parameters:: part - the part that the note is played by; control - the number of the controller; value - 8.8 bit fixed point signed controller specific value
Returns:: the stuffed representation of this type of extended music event.

stuffXKnobEvent

 public static long stuffXKnobEvent(int part,
                                    int knob,
                                    int value)

Returns a long that is the stuffed representation of the extended note music event. Extended music events are 2 big endian ints stuffed into a long.

Parameters:: part - the part that the knob is applied too; knob - the knob; value - the new value for the specified knob
Returns:: the stuffed representation of this type of extended music event.

eventType

 public static int eventType(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the event type.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

part

 public static int part(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the part number.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

xPart

 public static int xPart(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the part number.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

restDuration

 public static int restDuration(int x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the rest duration.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

notePitch

 public static int notePitch(int x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

noteVelocity

 public static int noteVelocity(int x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

noteDuration

 public static int noteDuration(int x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

xNotePitch

 public static int xNotePitch(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the note pitch.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

xNoteVelocity

 public static int xNoteVelocity(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the note velocity.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

xNoteDuration

 public static int xNoteDuration(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the note duration.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

controlController

 public static int controlController(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the controller number.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

controlValue

 public static int controlValue(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the controller's specified value.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

xControlController

 public static int xControlController(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

xControlValue

 public static int xControlValue(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the controller number.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

markerSubtype

 public static int markerSubtype(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the marker's sub type.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

markerValue

 public static int markerValue(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the marker's value.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

xKnobValue

 public static int xKnobValue(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

xKnobID

 public static int xKnobID(long x)

Given a stuffed big-endian order QuickTime extended music event this method will extract the knob's value.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the extended music event

generalSubtype_Footer

 public static int generalSubtype_Footer(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the general event's sub type from the footer of the general event.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

generalLength

 public static int generalLength(int x)

Given a stuffed big-endian order QuickTime music event this method will extract the general event's length from either header or the footer of the general event.

Parameters:: x - the stuffed big-endian music event
Returns:: the desired sub field of the music event

setSize

 public void setSize(int newSize) throws UtilException

Resets the size of the MusicData object to the new size (in bytes). The end of sequence marker is inserted in the last four bytes of the MusicData object.

Parameters:: newSize - - the new size of the MusicData object.
Overrides:: setSize in class QTHandle

getMusicEvent

 public int getMusicEvent(int offset) throws QTException

Returns the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.

Parameters:: offset - - the number of ints in the header
Returns:: the big endian ordered music event
Throws: QTException: if the offset would get data past the end of the MusicData

setMusicEvent

 public void setMusicEvent(int offset,
                           int musicData) throws QTException

Sets the big endian ordered stuffed QuickTime music event at the specified number of ints into the MusicData.

An application can only set the last four bytes if the value of the musicData in this case is the end of sequence marker - this is generally not required as it will be set by the constructor and setSize calls.

Parameters:: offset - - the number of ints in the header; musicData - the big endian ordered music event
Throws: QTException: if the offset would set data past the end of the MusicData

getXMusicEvent

 public long getXMusicEvent(int offset) throws QTException

Returns the stuffed QuickTime extended music event at the specified number of ints into the MusicData. Extended music events are two big endian ints stuffed into a long.

Parameters:: offset - - the number of ints in the header
Returns:: the music event - two big endian ints stuffed into a long
Throws: QTException: if the offset would get data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not an extended music event.

setXMusicEvent

 public void setXMusicEvent(int offset,
                            long musicData) throws QTException

Sets the stuffed QuickTime extended music event at the specified number of ints into the MusicData. Extended music events are two big endian ints stuffed into a long.

Parameters:: offset - - the number of ints in the header; musicData - the music event - two big endian ints stuffed into a long
Throws: QTException: if the offset would set data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not an extended music event.

setNoteRequest

 public void setNoteRequest(int offset,
                            int partNumber,
                            NoteRequest nr) throws QTException

Copies the NoteRequest data to the specified offset (numer of ints) into the MusicData. This will also setup the note request header and tail values - the part number is used to associate the given note request with a part reference in the concommitant music data.

When a note request event is stuffed into music data it is surrounded by two ints:

0xFnnn0017 where nnn is the part number - signifies start of note request event (0x0017 is the size of a note request event)
the note request data
0xC0010017 -> signifies end of note request event

Thus when calculating offsets for the position in the MusicData for a second NoteRequest event it is (given that the first note request is event is at the start of the music data and its offset is 1 as the header event takes up the first entry):
nextNoteEventOffset = StdQTConstants.kNoteRequestHeaderEventLength
The size (the number of ints) of a NoteRequest event (inc. header and footer) is supplied as the StdQTConstants.kNoteRequestHeaderEventLength constant in this class.

Parameters:: offset - - the number of music events (ints) into the header; partNumber - - the partNumber that is associated with this note request. The partNumber must be in the range of 0 to 0xFFF - the method will itself do the bit shifting required for the noteRequestEvent; nr - the NoteRequest to copy
Throws: QTException: if the offset would set data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.

getNoteRequest

 public NoteRequest getNoteRequest(int offset) throws QTException

Returns a NoteRequest object from the specified offset (numer of ints) into the MusicData. This checks to see if the data at that offset is a valid NoteRequest structure - if not a paramErr is thrown. Thus if retrieving a previously set NoteRequest the offset should take into account the addition of the head and tail fields of the setNoteRequest.

Parameters:: offset - - the number of ints in the header
Returns:: the NoteRequest
Throws: QTException: if the offset would get data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.

setAtomicInstrument

 public void setAtomicInstrument(int offset,
                                 int partNumber,
                                 AtomicInstrument ai) throws QTException

Copies the AtomicInstrument data to the specified offset (numer of ints) into the MusicData. This will also setup the atomic instrument header and tail values - the part number is used to associate the given instrument with a part reference in the concommitant music data.

When an AtomicInstrument event is stuffed into music data it is surrounded by two music events (ints):

0xFnnnxxxx where nnn is the part number - signifies start of note request event (xxxx is the size of an atomic instrument + head and tail event)
the AtomicInstrument data
0xC006xxxx -> signifies end of atomic instrument event (xxxx is the identical size as the header)

Thus when calculating offsets for the position in the MusicData for a second AtomicInstrument event it is:
nextAtomicInstOffset = sizeOfPreviousGeneralEvent + 1 (where 1 is the header event for the ai you are setting)

Parameters:: offset - - the number of ints into the header; partNumber - - the partNumber that is associated with this atomic instrument. The partNumber must be in the range of 0 to 0xFFF - the method will itself do the bit shifting required for the noteRequestEvent; ai - the AtomicInstrument to copy
Throws: QTException: if the offset would set data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.

getAtomicInstrument

 public AtomicInstrument getAtomicInstrument(int offset) throws QTException

Returns an AtomicInstrument from the specified offset (numer of ints) into the MusicData. This checks to see if the data at that offset is a valid AtomicInstrument structure - if not a paramErr exception is thrown Thus if retrieving a previously set AtomicInstrument the offset should take into account the addition of the head and tail fields of the AtomicInstrument event.

Parameters:: offset - - the number of ints in the header
Returns:: an AtomicInstrument
Throws: QTException: if the offset would get data past the end of the MusicData minus 4 bytes which is the end of sequence marker - which is not a general music event.

All Packages  Class Hierarchy  This Package  Previous  Next  Index